---
title: "Workflow"
space: "Frappe Framework"
url: "https://support.aakvatech.com/Frappe Framework/workflow"
updated: "2026-07-22"
---

## 1. Overview

This Workflow module allows you to define, manage, and automate document approval processes in ERPNext. It includes state transitions, role-based permissions, and docstatus controls, integrated with backend validation and frontend visual tools (Workflow Builder).

---

## 2. Key Features

- Visual Workflow Builder (drag-and-drop interface)
- Support for custom workflow states and transitions
- Auto creation of hidden state fields in documents
- Role-based action control
- Email notifications on transitions
- Bulk workflow approval handling
- Enforcement of valid state transitions

---

## 3. Pre-Requisites

- Must have **System Manager** role to create or edit Workflows.
- Target DocType should not be Single or Child Table.
- The document must include a field for workflow state (`workflow_state_field`) or it will be created automatically.

---

## 4. Step-by-Step Usage

1. **Navigate to**: *Workflow > New*.
2. **Fill in Basic Info**:
   - Workflow Name
   - Document Type
3. **Set States**:
   - Define each workflow state
   - Assign `docstatus`: 0 (Saved), 1 (Submitted), 2 (Cancelled)
4. **Set Transitions**:
   - Define which state can move to another
   - Assign user roles and actions
5. **Activate Workflow**:
   - Enable "Is Active" to apply it (automatically deactivates others for the same DocType).
6. **Use Workflow Builder (Optional)**:
   - Access visual editor for design and positioning of states.
7. **Save and Test**:
   - Test transitions on the respective document type.

---

## 5. Script Customizations

- **Python (workflow.py)**:
  - `apply_workflow`: Applies transitions and updates docstatus.
  - `get_transitions`: Fetches permitted transitions per user role.
  - `bulk_workflow_approval`: Background processing for mass updates.
- **Client JS (workflow.js)**:
  - Enhances form UI, shows orphaned states, integrates with builder.
  - Adds validation for transitions and roles.
- **DocType JSON (workflow.json)**:
  - Controls schema, field definitions, and default behavior.

---

## 6. Troubleshooting (Common Errors and Resolutions)

| Error Message | Reason | Resolution |
|---------------|--------|------------|
| *"Workflow State not set"* | Missing workflow_state value | Ensure workflow_state_field is set in the document |
| *"Cannot change state of Cancelled Document"* | Transition from docstatus=2 attempted | Remove invalid transition in configuration |
| *"Submitted Document cannot be converted back to draft"* | Invalid transition 1 → 0 | Update transition rules |
| *"Workflow must have at least one state and transition"* | Missing essential definitions | Define at least one state and one transition |
| *"Not a valid Workflow Action"* | Action not permitted for user or state | Check role assignments in the transition |

---

## 7. User Roles and Permissions

- **Only roles assigned in transitions** can perform workflow actions.
- **System Manager** can create or edit workflows.
- **Self approval restriction**: If `allow_self_approval` is not checked, users cannot approve their own documents.

---

## 8. Key Notes

- Workflows are **docstatus-aware**: transitions enforce legal status changes.
- The system automatically deactivates old workflows when a new one is activated for the same DocType.
- Transition conditions can be defined using Python expressions (evaluated safely).
- Orphaned states are detected and shown to the user for correction.

---

## 9. What Business Process Pain Point Does It Help Remove

This module eliminates **manual and inconsistent approval processes** by introducing:

- Controlled document status flow
- Role-based transitions
- Audit trail of state changes
- Automated field updates and notifications

It ensures **compliance, transparency, and operational efficiency** across document-driven workflows in the ERP system.